home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc™ Source Code / Storage / Bento / CM / Refs.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-28  |  5.6 KB  |  139 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        Refs.h
  3.  
  4.     Contains:    Container Manager Object Reference Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1992-1994 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     8/26/94    EL        #1181622 Ownership update.
  15.          <2>      5/9/94    MB        #1162181: Changes necessary to install MMM.
  16.          <1>      2/3/94    EL        first checked in
  17.  
  18.     To Do:
  19. */
  20.  
  21. /*---------------------------------------------------------------------------*
  22.  |                                                                           |
  23.  |                            <<<    Refs.h    >>>                           |
  24.  |                                                                           |
  25.  |               Container Manager Object Reference Interfaces               |
  26.  |                                                                           |
  27.  |                               Ira L. Ruben                                |
  28.  |                                 10/25/92                                  |
  29.  |                                                                           |
  30.  |                     Copyright Apple Computer, Inc. 1992-1994              |
  31.  |                           All rights reserved.                            |
  32.  |                                                                           |
  33.  *---------------------------------------------------------------------------*
  34.  
  35.  This file defines the routines needed by others to access object references maintained by
  36.  the API Reference operations defined in CMReferenceOps.c.  Object references are
  37.  "pointers" (i.e., object IDs) to other objects from a value (CMValue) that contains data
  38.  that refers to those objects.  The data is in the form of a CMReference "key".  The
  39.     CMRefOps.c    API routines manipulate those key/object (ID) associations.
  40.  
  41.  The associations are maintained in a list as value data for a uniquely typed value in a
  42.  private object "tied" to the value through a pointer (refDataObject) in the value header.
  43. */
  44.  
  45.  
  46. #ifndef __REFERENCES__
  47. #define __REFERENCES__
  48.  
  49. #ifndef __CMTYPES__
  50. #include "CMTypes.h"
  51. #endif
  52. #ifndef __CM_API_TYPES__
  53. #include "CMAPITyp.h"
  54. #endif
  55. #ifndef __LISTMGR__
  56. #include "ListMgr.h"
  57. #endif
  58. #ifndef __GLOBALNAMES__
  59. #include "GlbNames.h"   
  60. #endif
  61. #ifndef __CONTAINEROPS__
  62. #include "Containr.h"  
  63. #endif
  64. #ifndef __TOCENTRIES__
  65. #include "TOCEnts.h"   
  66. #endif
  67.  
  68. struct TOCValueHdr;
  69.                                                                     
  70.                                                                     CM_CFUNCTIONS
  71.  
  72. /* References are recorded in a value's recording object as a sequence of entries with    */
  73. /* the following layout...                                                                                                                            */
  74.  
  75. struct ReferenceData {                                                /* Layout of recording objects ref data:    */
  76.     CMReference        key;                                                    /*         reference key                                                */
  77.     CM_UCHAR objectID[sizeof(CMReference)];/*        associated referenced object ID            */
  78. };
  79. typedef struct ReferenceData ReferenceData;
  80.  
  81.  
  82. /* The actual reference list data is maintained as value data for the recoding object.    */
  83. /* To increase efficiency, the data is read into memory the first time it's accessed.        */
  84. /* From that point on, all updates to the actual data are "shadowed" in the in-memory        */
  85. /* list.  The updating can't be avoided (so updating, e.g., touches, etc. work                     */
  86. /* correctly). But at least the searches can be made to not be I/O bound! The following */
  87. /* describes the layout for the in-memory list.  There's a list header and the list         */
  88. /* entries themselves.  It's a doubly linked list so that the ListMgr.c routines can         */
  89. /* used and to make deletion easier.                                                                                                       */
  90.  
  91. struct RefDataShadowEntry {                                        /* Reference list data shadow entries:        */
  92.     ListLinks         refDataLinks;                                    /*        links to next/prev data(must be 1st)*/
  93.     CM_ULONG        key;                                                    /*        ref key (internalized CMReference)    */
  94.     CMObjectID         objectID;                                            /*        associated object ID                                */
  95. };
  96. typedef struct RefDataShadowEntry RefDataShadowEntry, *RefDataShadowEntryPtr;
  97.  
  98.  
  99. /* The list header is pointed to by the SAME value header field usually used to point     */
  100. /* to the recording object (refDataObject).  However, a union is used to use a more         */
  101. /* appropriate name (refShadowList).  We can always tell which is which because the            */
  102. /* refShadowList will only have meaning in the recording object's value itself which is    */
  103. /* uniquely typed (CM_StdObjID_ObjRefData).      If the field is not NULL, but not that        */
  104. /* type, then we know we have a pointer to the recording object because in all other         */
  105. /* values this field is NULL.  To aid in using these fields in a value header, the             */
  106. /* following macros are provided.                                                                                                                */
  107.  
  108. #define RefDataObject(v)        (((TOCValueHdrPtr)(v))->references.refDataObject)
  109. #define RefShadowList(v)        (((TOCValueHdrPtr)(v))->references.refShadowList)
  110.  
  111. #define HasRefDataObject(v)    (RefDataObject(v) != NULL && \
  112.                                                           ((TOCValueHdrPtr)(v))->typeID != CM_StdObjID_ObjRefData)
  113.  
  114. #if CMSHADOW_LIST
  115. #define HasRefShadowList(v)    (RefShadowList(v) != NULL && \
  116.                                                          ((TOCValueHdrPtr)(v))->typeID == CM_StdObjID_ObjRefData)
  117. #else
  118. #define HasRefShadowList(v)    0
  119. #endif
  120.  
  121.  
  122. #if CMSHADOW_LIST
  123.  
  124. void cmDeleteRefDataShadowList(struct TOCValueHdr *refDataValueHdr);
  125.     /*
  126.     This routine is called to delete the entire shadow list pointed to from the specified
  127.     recording object's value header.  It is used for clearing the list during error recovery
  128.     and value (header) deletions.
  129.     
  130.     Note, generally the caller should have done a HasRefShadowList(refDataValueHdr) prior to
  131.     calling this routine to make sure that the value header is indeed a recording object
  132.     value header.
  133.     */
  134.  
  135. #endif
  136.  
  137.                                                           CM_END_CFUNCTIONS
  138. #endif
  139.